<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:epub="http://www.idpf.org/2007/ops" lang="en" xml:lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Windows version 5.7.28"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>ABI for the Arm Architecture Advisory Note - SP must be
8-byte aligned on entry to AAPCS-conforming functions - ABI 2018Q4
documentation</title>

<meta name="keywords" content="Fast Models"/></head>
<body>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div id="abi-for-the-arm-architecture-advisory-note-sp-must-be-8-byte-aligned-on-entry-to-aapcs-conforming-functions">
<h2>ABI for the Arm Architecture Advisory Note - SP must be 8-byte
aligned on entry to AAPCS-conforming functions</h2>
<p>Document number: IHI 0046C, current through ABI release
2018Q4</p>
<p>Date of Issue: 21<sup>st</sup> December 2018</p>

<div>
<div>
<div>
<div id="preamble">
<h2>Preamble</h2>
<div>
<div>
<div>
<div id="abstract">
<h3>Abstract</h3>
<p>This advisory note discusses a hitherto little noticed
consequence of the ABI requirement for natural alignment for
primitive data of size 1, 2, 4, and 8 bytes, and its implications
for:</p>
<ul>
<li>Low level exception-handling code running on:
<ul>
<li>and R profiles of version 7 of the Arm architecture.</li>
<li>Versions of the Arm architecture earlier than version 7.</li>
</ul>
</li>
<li>Code that might be entered directly through an Armv7M exception
vector.</li>
<li>Tool chains that generate such code.</li>
</ul>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="keywords">
<h3>Keywords</h3>
<p>ABI for the Arm architecture, advisory note</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="how-to-find-the-latest-release-of-this-specification-or-report-a-defect-in-it">
<h3>How to find the latest release of this specification or report
a defect in it</h3>
<p>Please check the Arm Developer site (<a href="https://developer.arm.com/products/software-development-tools/specifications">https://developer.arm.com/products/software-development-tools/specifications</a>)
for a later release if your copy is more than one year old.</p>
<p>Please report defects in this specification to <em>arm</em> dot
<em>eabi</em> at <em>arm</em> dot <em>com</em>.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="proprietary-notice">
<h3>Proprietary notice</h3>
<p>Arm, Thumb, RealView, Arm7TDMI and Arm9TDMI are registered
trademarks of Arm Limited. The Arm logo is a trademark of Arm
Limited. Arm9, Arm926EJ-S, Arm946E-S, Arm1136J-S, Arm1156T2F-S,
Arm1176JZ-S, Cortex, and Neon are trademarks of Arm Limited. All
other products or services mentioned herein may be trademarks of
their respective owners.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="contents">
<h3>Contents</h3>
<div>
<div>
<div>
<div id="id1">
<p>Contents</p>
<ul>
<li><a href="index.html#abi-for-the-arm-architecture-advisory-note-sp-must-be-8-byte-aligned-on-entry-to-aapcs-conforming-functions" id="id2">ABI for the Arm® Architecture Advisory Note -
SP must be 8-byte aligned on entry to AAPCS-conforming
functions</a>
<ul>
<li><a href="index.html#preamble" id="id3">Preamble</a>
<ul>
<li><a href="index.html#abstract" id="id4">Abstract</a></li>
<li><a href="index.html#keywords" id="id5">Keywords</a></li>
<li><a href="index.html#how-to-find-the-latest-release-of-this-specification-or-report-a-defect-in-it" id="id6">How to find the latest release of this
specification or report a defect in it</a></li>
<li><a href="index.html#proprietary-notice" id="id7">Proprietary
notice</a></li>
<li><a href="index.html#contents" id="id8">Contents</a></li>
</ul>
</li>
<li><a href="index.html#about-this-document" id="id9">About This
Document</a>
<ul>
<li><a href="index.html#change-control" id="id10">Change
control</a></li>
<li><a href="index.html#references" id="id11">References</a></li>
<li><a href="index.html#terms-and-abbreviations" id="id12">Terms
and abbreviations</a></li>
</ul>
</li>
<li><a href="index.html#the-problem-and-how-to-avoid-it" id="id13">The Problem and How to Avoid it</a>
<ul>
<li><a href="index.html#the-need-to-align-sp-to-a-multiple-of-8-at-conforming-call-sites" id="id14">The need to align SP to a multiple of 8 at
conforming call sites</a></li>
<li><a href="index.html#possible-consequences-of-sp-misalignment" id="id15">Possible consequences of SP misalignment</a></li>
<li><a href="index.html#corrective-steps" id="id16">Corrective
steps</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="about-this-document">
<h2>About This Document</h2>
<div>
<div>
<div>
<div id="change-control">
<h3>Change control</h3>
<div>
<div>
<div>
<div id="current-status-and-anticipated-changes">
<h4>Current status and anticipated changes</h4>
<p>The following support level definitions are used by the Arm ABI
specifications:</p>
<ul>
<li>ReleaseArm considers this specification to have enough
implementations, which have received sufficient testing, to verify
that it is correct. The details of these criteria are dependent on
the scale and complexity of the change over previous versions:
small, simple changes might only require one implementation, but
more complex changes require multiple independent implementations,
which have been rigorously tested for cross-compatibility. Arm
anticipates that future changes to this specification will be
limited to typographical corrections, clarifications and compatible
extensions.</li>
<li>BetaArm considers this specification to be complete, but
existing implementations do not meet the requirements for
confidence in its release quality. Arm may need to make
incompatible changes if issues emerge from its implementation.</li>
<li>AlphaThe content of this specification is a draft, and Arm
considers the likelihood of future incompatible changes to be
significant.</li>
</ul>
<p>All content in this document is at the "Release" quality
level.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="change-history">
<h4>Change history</h4>
<table>
<colgroup>
<col width="6%"/>
<col width="32%"/>
<col width="3%"/>
<col width="59%"/></colgroup>
<thead valign="bottom">
<tr>
<th>Issue</th>
<th>Date</th>
<th>By</th>
<th>Change</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td>0.01</td>
<td>28<sup>th</sup> February 2006</td>
<td>LS</td>
<td>DRAFT for internal comment.</td>
</tr>
<tr>
<td>0.1</td>
<td>3<sup>rd</sup> March 2006</td>
<td>LS</td>
<td>CONFIDENTIAL version for limited release.</td>
</tr>
<tr>
<td>1.0</td>
<td>20<sup>th</sup> March 2006</td>
<td>LS</td>
<td>Open access version.</td>
</tr>
<tr>
<td>A</td>
<td>25<sup>th</sup> October 2007</td>
<td>LS</td>
<td>Document renumbered (formerly GENC-007024 v1.0).</td>
</tr>
<tr>
<td>B</td>
<td>23<sup>rd</sup> October 2009</td>
<td>LS</td>
<td>Updated the reference to the Arm ARM; reviewed use of
terminology.</td>
</tr>
<tr>
<td>2018Q4</td>
<td>21<sup>st</sup> December 2018</td>
<td>OS</td>
<td>Minor typographical fixes, updated links.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="references">
<h3>References</h3>
<p>This document refers to the following documents.</p>
<table>
<colgroup>
<col width="19%"/>
<col width="42%"/>
<col width="39%"/></colgroup>
<thead valign="bottom">
<tr>
<th>Ref</th>
<th>Document number / External URL</th>
<th>Title</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><a href="https://developer.arm.com/docs/ihi0042/latest">AAPCS</a></td>
<td>Arm IHI 0042F</td>
<td>Procedure Call Standard for the Arm Architecture</td>
</tr>
<tr>
<td><a href="https://developer.arm.com/products/architecture/m-profile/docs/ddi0403/e/armv7-m-architecture-reference-manual">
Armv7ARM_M</a></td>
<td>Arm DDI 0403E</td>
<td>Arm DDI 0406: Arm Architecture Reference Manual Arm v7-A and
Arm v7-R edition</td>
</tr>
<tr>
<td><a href="https://developer.arm.com/docs/ddi0406/c/arm-architecture-reference-manual-armv7-a-and-armv7-r-edition">
Armv7ARM_AR</a></td>
<td>Arm DDI 0406C</td>
<td>Arm DDI 0403C: Armv7-M Architecture Reference Manual</td>
</tr>
<tr>
<td><a href="https://developer.arm.com/docs/ddi0100/latest/armv5-architecture-reference-manual">
Armv5ARM</a></td>
<td>Arm DDI 0100E, ISBN 0 201 737191</td>
<td>The Arm Architecture Reference Manual, 2nd edition, edited by
David Seal, published by Addison-Wesley.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="terms-and-abbreviations">
<h3>Terms and abbreviations</h3>
<p>This advisory note uses the following terms and
abbreviations.</p>
<ul>
<li>AAPCSProcedure Call Standard for the Arm Architecture</li>
<li>ABI
<p>Application Binary Interface:</p>
<ol>
<li>The specifications to which an executable must conform in order
to execute in a specific execution environment. For example, the
<cite>Linux ABI for the Arm Architecture.</cite></li>
<li>particular aspect of the specifications to which independently
produced relocatable files must conform in order to be statically
linkable and executable. For example, the <a href="https://developer.arm.com/docs/ihi0041/latest">C++ ABI for the Arm
Architecture</a>, the <a href="https://developer.arm.com/docs/ihi0043/latest">Run-time ABI for
the Arm Architecture</a>, the <a href="https://developer.arm.com/docs/ihi0039/latest">Library ABI for the
Arm Architecture</a>.</li>
</ol>
</li>
<li>Q-o-IQuality of Implementation - a quality, behavior,
functionality, or mechanism not required by this standard, but
which might be provided by systems conforming to it. Q-o-I is often
used to describe the tool-chain-specific means by which a standard
requirement is met.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="the-problem-and-how-to-avoid-it">
<h2>The Problem and How to Avoid it</h2>
<div>
<div>
<div>
<div id="the-need-to-align-sp-to-a-multiple-of-8-at-conforming-call-sites">
<h3>The need to align SP to a multiple of 8 at conforming call
sites</h3>
<p>The Procedure Call Standard for the Arm Architecture [<a href="https://developer.arm.com/docs/ihi0042/latest">AAPCS</a>] requires
primitive data types to be naturally aligned according to their
sizes (for size = 1, 2, 4, 8 bytes). Doing otherwise creates more
problems than it solves.</p>
<p>In return for preserving the natural alignment of data,
conforming code is permitted to rely on that alignment. To support
aligning data allocated on the stack, the stack pointer (SP) is
required to be 8-byte aligned on entry to a conforming function. In
practice this requirement is met if:</p>
<ul>
<li>
<p>At each call site, the current size of the calling
function's stack frame is a multiple of 8 bytes.</p>
<p>This places an obligation on compilers and assembly language
programmers.</p>
</li>
<li>
<p>SP is a multiple of 8 when control first enters a
program.</p>
<p>This places an obligation on authors of low level OS, RTOS, and
runtime library code to align SP at all points at which control
first enters a body of (AAPCS-conforming) code.</p>
</li>
</ul>
<p>In turn, this requires the value of SP to be aligned to 0 modulo
8:</p>
<ul>
<li>By exception handlers, before calling AAPCS-conforming
code.</li>
<li>By OS/RTOS/run-time system code, before giving control to an
application.</li>
</ul>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="possible-consequences-of-sp-misalignment">
<h3>Possible consequences of SP misalignment</h3>
<p>The possible consequences of not aligning SP properly depend on
the architecture version and the characteristics of the code (and,
hence on the behavior of the code generator). Possible consequences
include:</p>
<ul>
<li>Alignment fault or UNPREDICTABLE behavior.</li>
<li>Application failure.</li>
</ul>
<div>
<div>
<div>
<div id="alignment-fault-or-unpredictable-behavior">
<h4>Alignment fault or UNPREDICTABLE behavior</h4>
<p>For architecture Armv5TE (in particular, for Intel XScale
processors) and architecture Armv6 with CP15 register 1 A and U
bits [Arm ARM, G3.1, Unaligned access support] configured to
emulate Armv5TE:</p>
<ul>
<li>An LDRD or STRD using a stack address presumed by a code
generator to be 0 modulo 8, but actually 4 modulo 8, could cause an
Alignment Fault or show UNPREDICTABLE behavior.</li>
</ul>
<p>This failure cannot occur in code generated for architectures
earlier than Armv5TE (no LDRD or STRD) or on processors conforming
to architecture Armv7 or later (which cannot cause an alignment
fault when the effective address of an LDRD or STRD is 4 modulo
8).</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="application-failure">
<h4>Application failure</h4>
<p>An application failure might occur if SP is not 0 modulo 8 on
entry to each AAPCS-conforming function and the program contains an
interface such that:</p>
<ul>
<li>Code on one side of the interface evaluates the presumed
alignment of an 8-byte aligned, stack allocated datum at compile
time.</li>
<li>Code on the other side of the interface evaluates the actual
alignment of the datum at run time.</li>
</ul>
<p>The interface defined by the C library's stdarg.h macros
va_start and va_arg gives us a concrete example of how an
application might fail.</p>
<ul>
<li>The compiler evaluates the presumed alignment of a parameter
value passed to a variadic function at compile time. This
determines whether to insert an additional padding word before an
8-byte aligned parameter value. Parameter values beyond the fourth
word are passed to the callee via the stack and a variadic callee
often pushes earlier parameter values onto the stack (to support
uniform treatment of va_list types).</li>
<li>Code generated by the va_arg macro evaluates the corresponding
actual alignment at run time. This determines whether or not to
skip a padding word preceding an 8-byte aligned parameter
value.</li>
</ul>
<p>more cautious than usual implementation of va_start and va_arg
can avoid this problem and operate correctly whether SP is 0 or 4
modulo 8 (2.3.2.3).</p>
<p>In general, a compiler cannot detect whether similar code exists
in an application. An application containing such code can fail if
SP is not properly aligned.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="corrective-steps">
<h3>Corrective steps</h3>
<div>
<div>
<div>
<div id="operating-systems-and-run-time-environments">
<h4>Operating systems and run-time environments</h4>
<p>As stated in <a href="index.html">The need to align
SP to a multiple of 8 at conforming call sites</a>, operating
systems and other run-time environments must ensure that SP is a
multiple of 8 before calling AAPCS-conforming code. Alternatively
the system must ensure that:</p>
<ul>
<li>
<p>The code it calls makes no use of 8-byte aligned,
stack allocated data (see <a href="index.html">Safe
option not to align SP</a>).</p>
<p>For example, an operating system might require that no 8-byte
types be manipulated by exception handling code, and software
development tools for that OS might support this proscription
(<a href="index.html">Safe option not to align
SP</a>).</p>
</li>
<li>
<p>If the architecture is V5TE or V6 configured to
give V5TE alignment behavior, the compiler used to build the code
must not have generated LDRD/STRD in place of a pair of LDR/STR to
consecutive locations.</p>
</li>
</ul>
<p>This requirement extends to operating systems and run-time code
for all architecture versions prior to Armv7 and to the A, R and M
architecture profiles thereafter. Special considerations associated
with Armv7M are discussed in <a href="index.html">Special considerations for Cortex-M
based applications</a>.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="software-development-tools">
<h4>Software development tools</h4>
<div>
<div>
<div>
<div id="option-to-align-sp-on-entry-to-designated-functions">
<h5>Option to align SP on entry to designated functions</h5>
<p>To support legacy execution environments in which SP is not
properly aligned, compilers should offer an option to generate code
to align SP to a multiple of 8 on entry to designated
functions.</p>
<p>The means by which a function might be designated for special
treatment is a quality of implementation (Q-o-I). Plausible means
include the use of pseudo storage class specifiers like __irq or
__declspec(irq), or attributes like __attribute__((irq)), in a
function's declaration.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="safe-option-not-to-align-sp">
<h5>Safe option not to align SP</h5>
<p>To support safely not using the SP alignment option, compilers
should offer an option (Q-o-I) to:</p>
<ul>
<li>
<p>Not generate LDRD/STRD.</p>
</li>
<li>
<p>Fault the use of 8-byte aligned, stack allocated
data.</p>
<p>(8-byte aligned parameters to variadic functions need not be
faulted if the tool chain implements the repair described in
<a href="index.html">Repair of va_start and
va_arg</a>).</p>
</li>
<li>
<p>Or, if that is too difficult, fault all uses of
8-byte data types.</p>
</li>
</ul>
<p>program that makes no us of LDRD/STRD cannot suffer the failure
described in <a href="index.html">Alignment fault or
UNPREDICTABLE behavior</a>.</p>
<p>program that makes no use of 8-byte aligned, stack allocated
data cannot suffer the failure described in <a href="index.html">Application failure</a>. And a program
that makes no use 8-byte types certainly makes no use of 8-byte
aligned, stack allocated data.</p>
<p>Assembly language programmers must, of course, certify the
safety of their own code.</p>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="repair-of-va-start-and-va-arg">
<h5>Repair of va_start and va_arg</h5>
<p>To avoid injecting a fault into their users' programs in
execution environments that do not correctly align SP, software
development tools should offer an option (Q-o-I) to repair the C
library's stdarg.h macros va_start and va_arg, as follows.</p>
<p>(We assume va_start expands to a call to the intrinsic function
__va_start, and va_arg to a call to __va_arg. It is already very
difficult - or impossible - to implement va_start and va_arg in a
way that evaluates each argument only once - as required by the C
standard - without the assistance of at least one intrinsic
function).</p>
<p>__va_start should return a pointer value ap with bit[1] set if
SP was 4 modulo 8 on entry to the containing function.</p>
<ul>
<li>The function containing the call to __va_start has the variadic
parameter list allocated in the stack frame.</li>
<li>Because arguments are guaranteed to be 4-byte aligned (by C's
argument promotion rules and the AAPCS requirement that SP be
4-byte aligned at all instants), bits[1:0] of ap are otherwise
0.</li>
<li>Coding the SP-misaligned case as 1 produces a __va_start
compatible with an ordinary (not repaired) __va_arg in conforming
environments in which SP is 0 modulo 8 at function entry.</li>
</ul>
<p>If T is a data type requiring 8-byte alignment, __va_arg(ap, T)
must increment the pointer it calculates by 4 bytes (to skip a
padding word inserted at compile time) if:</p>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<pre>(bit[1] of ap is 0 and bit[2] of ap is 1) or (bit[1] of ap is 1 and bit[2] of ap is 0).
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<p>Whatever the sort of T, __va_arg(ap, T) must clear bit 1 of the
pointer it calculates before dereferencing it.</p>
<ul>
<li>This implementation of __va_arg is compatible with an ordinary
(not repaired) __va_start in conforming environments in which SP is
0 modulo 8 at function entry and bit 1 of ap is always 0.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div id="special-considerations-for-cortex-m-based-applications">
<h4>Special considerations for Cortex-M based applications</h4>
<p>Armv7M is unique in making it possible (absent the problem
discussed in this advisory note) to attach an AAPCS-conforming
function directly to an exception vector.</p>
<p>(Under previous architecture versions and other architecture
strands, some 'glue' code is required between an exception vector
and an AAPCS-conforming function. Usually, an OS, RTOS, or run-time
system provides this code. Considerations relating to such systems
were discussed in <a href="index.html">Operating
systems and run-time environments</a>).</p>
<p>Cortex-M3 is the first implementation of Armv7M.</p>
<ul>
<li>
<p>Revision 0 of Cortex-M3 (CM3_r0) does not align SP
to a multiple of 8 on entry to exceptions.</p>
<p>Users of CM3_r0 must take appropriate precautions if the
correctness of their software might depend on the alignment of
stack-allocated data presumed by development tools to be 8-byte
aligned.</p>
</li>
<li>
<p>Revision 1 of Cortex-M3 will offer a configurable
option to align SP to a multiple of 8 on entry to exceptions.</p>
</li>
<li>
<p>A future revision of the M profile architecture
will require SP to be 8-byte aligned on entry to exceptions.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div>
<div/>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
